10.8 AT^SISW Internet Service Write DataThe AT^SISW command triggers a write operation (upload) and queries the amount of data already sent, but not acknowledged at the TCP layer. The write operation may be run in binary mode, or in interactive text mode.
The AT^SISW write command may return the following errors:
• "+CME ERROR: operation failed" if there is a problem on application, socket, PPP or GPRS/GSM level. The AT^SISE command and the "^SIS" URC offer additional error information.
• "+CME ERROR: operation temporary not allowed" e.g. if the service has not network resources allocated.
• "+CME ERROR: operation not allowed" e.g. if the service is not configured.
+CME ERROR: <err>
Data availability status of the Internet service configured with AT^SISS has changed. The URC is issued when the service is ready to accept new user data.
The URC is disabled in polling mode. See AT^SCFG, parameter "Tcp/WithURCs", <tcpWithUrc>.
<srvProfileId>(num)<srvProfileId> 0 ... 9 specified with AT^SISS.
<reqWriteLength>(num)Specifies the number of bytes to be sent with AT^SISW or, if set to 0, requests the amount of data already sent with AT^SISW but not yet acknowledged:
• Parameter <reqWriteLength> may be 1...1500 bytes to specify the amount of data to be sent with AT^SISW.
• If parameter <reqWriteLength> equals 0, AT^SISW does not expect any data, but a normal query is perfomed. This allows the application to explictly request, in particular at the end of an upload job, the amount of unacknowledged data at the TCP layer indicated by <unackData>.
• In interactive text mode, <reqWriteLength> must be set to any value greater than 0 (but not necessarily the precise number of bytes). If set to 0 in interactive text mode, <reqWriteLength> would be interpreted as query for unacknowledged data and, thus, prevent data transfer.
- <reqWriteLength>=0 can be used to send an empty UDP packet;
- it is recommended that the size of each data packet be limited to 1472 bytes. Otherwise, it is possible that the following URC occurs: "^SIS: <id>, 0, 9, The supplied buffer was too small / large".
<eodFlag>(num)End of data indication flag.
Parameter is ignored for HTTP, POP3, FTP download, Socket with UDP protocol.End of data is signalled to the Internet Service. Further AT^SISW write commands return an error response. However, reading data may be possible. The <eodFlag> is effective only if the <reqWriteLength> equals <cnfWriteLength>, in particular if the <reqWriteLength> equals 0.
If <mode> equals 1 the <eodFlag> is effective only if the write operation has been finished with CTRL-Z.
<mode>(num)Interactive text mode
This mode allows the user to type and send 8-bit ASCII characters while the service is open. Ctrl-Z terminates data input and causes the data to be transferred.
Interactive text mode requires that the <reqWriteLength> is set to any value greater than 0 (though it is not necessary to specify the precise number of bytes). In this case the <cnfWriteLength> parameter indicates the maximum length of the data stream without control character CTRL-Z.
In interactive text mode, the following characters are predefined as control codes:
• ESC ("\x1b") aborts the command. An <eodFlag> is ignored in this case.The V.25 command ATE also controls the echo mode of the interactive text mode. If echo is enabled (ATE1) all characters are echoed until <cnfWriteLength> is reached. Any attempt to input further data ends up with the warning message 4001 indicated after the data stream has been completed with CTRL-Z, nevertheless all data within the range of <cnfWriteLength> will be sent. See also Section 10.13, Internet Service URC "^SIS". ATE0 disables the echo mode generally.
<optServParam>(str)Service specific parameter of the AT^SISW write command. If the Socket service is configured as UDP endpoint this parameter is mandatory and specifies the IP address (in dotted format) and the UDP port of the remote host. For each write request another IP address and UDP port may be given.
<cnfWriteLength>(num)Confirmed number of data bytes which can be transmitted via the Internet service configured in <srvProfileId>. In binary mode (see <mode>) this number may be less or equal to the value requested with <reqWriteLength>. The application has to deliver exactly the number of bytes indicated by <cnfWriteLength>. A 0 value means that no data can be written at this time, i.e. it serves as a flow control mechanism.
In interactive text mode, <cnfWriteLength> indicates the maximum number of bytes it can process. Characters above the indicated number are ignored.
<unackData>(num)Number of data bytes already sent but not yet acknowledged at the TCP layer.
The value is constantly changing until the entire upload job has completed. If the value equals 0 all data sent so far is acknowledged.
In binary mode, <unackData> includes the <cnfWriteLength> value of the pending write operation. Therefore, the very first write operation of an upload job returns identical values for <cnfWriteLength> and <unackData>.
This mechanism allows the host application to easily verify whether or not the remote host has successfully received the data.
Parameter is not applicable to HTTP, POP3, SMTP and Socket with UDP protocol. For these services the counter is always set to 0.
<urcCauseId>(num)Data transfer has been finished successfully and Internet service may be closed without loss of data.
• The AT^SISW write command must be terminated only with the ASCII character set with ATS3. The factory default for S3 is #13 (Carriage Return). Do not send any further characters after the S3 end-of-line identifier, until the response "^SISW" is received. This is necessary to avoid that any characters related to the AT command can be interpreted as being part of the data stream to be transferred. Also refer to Section 1.4, AT Command Syntax.
• If the Socket service is configured for use as UDP client and fixed size and the interactive text mode is active, the PDU length always equals the specified fixed length. If the input characters exceed the specified fixed length, then all surplus characters will be ignored. If the input characters are less than the specified fixed length, then the remaining range will be filled with "\0" bytes.
|